Make it easy to test-publish packages #2053

psrpinto · 2024-12-04T13:34:17Z

Previously, in #1924, I needed to test-publish a package without actually publishing it to NPM. At the time, I used an ad-hoc (and cumbersome) way to do so that got the job done (see PR description on #1924), but @adamziel suggested it could be useful to document such a process.

As such, this PR does three things:

Introduce a local package registry that runs in the developer's machine
Make it easy to switch the target registry of npm from npmjs.com to the local one, and vice-versa
Document how to publish packages, both to production (npmjs.com) and to the local registry

The rendered documentation is here.

Testing instructions

Please follow the instructions in the docs to publish packages to a local registry.

Summary of changes

Provide a script to start the local registry
Provide a script to clear the local registry (removes all data used by the local registry)
Provide a script to enable the local registry (makes npm commands target the local registry)
Provide a script to disable the local registry (makes npm commands target npmjs.com)
Add a hook that prevents committing npmrc when the local registry is enabled
Provide documentation on how to publish packages

Screen captures

Local package registry

Shows the UI of the local package registry, after some packages were test-published.

Docs

References

To prevent accidentally committing .npmrc with the registry set to local.

psrpinto

I've made a number of assumptions when documenting the release process, so the docs might not be correct. I appreciate any input you might have.

psrpinto · 2024-12-06T17:04:30Z

packages/docs/site/docs/main/contributing/code.md

+Playground's versioning strategy is to use the same version for all packages, **but** only packages that need to be released are bumped to the new version. As an example, lets consider the following scenario:
+
+-   All packages are currently at `v1.0.0`
+-   The following packages have changes since `v1.0.0`: `@wp-playground/cli` and `@wp-playground/remote`
+
+When we issue a new release, only `@wp-playground/cli` and `@wp-playground/remote` will be bumped to `v1.0.1`, and all other packages will remain at `v1.0.0`.


I'm not 100% this is correct, I appreciate any feedback you might have about this.

This is almost correct, I'd add a bit about dependencies, e.g. if we also updated @wp-playground/blueprints then @wp-playground/client would also be version bumped to consume the latest Blueprints version.

psrpinto · 2024-12-06T17:06:52Z

packages/docs/site/docs/main/contributing/code.md

+
+### Authenticating with npmjs.com
+
+TODO


I think I've heard someone (maybe @bgrgicak ?) mention that they were able to publish to npmjs.com from their local machine, but I'm not 100% sure of this. If you have done it before, could you comment here on how that process exactly works? Thanks in advance. I will then incorporate it into the docs.

We have a npm run release command that you can run locally. AFAIR it will ask you for npmjs.org credentials.

adamziel · 2024-12-10T09:22:07Z

.husky/pre-commit

+HAS_LOCAL_REGISTRY=$(git diff --cached --name-only .npmrc | xargs grep -n "registry=http://localhost:4873/")
+if [ -n "${HAS_LOCAL_REGISTRY}" ]; then
+	echo "The commit was rejected due to attempting to commit .npmrc with the registry set to the local registry."


Good check! I'm wondering – is it possible to use a file that's .gitignore-d instead of a versioned one like .npmrc?

Alternatively, could this focus more on the next step? As in tell the user to run npm run local-registry:disable

adamziel · 2024-12-10T09:26:54Z

packages/docs/site/docs/main/contributing/code.md

+npm run release
+```
+
+### Publishing to a local registry


H2 perhaps? No strong opinions

Suggested change

### Publishing to a local registry

## Publishing to a local registry

adamziel · 2024-12-10T09:29:39Z

package.json

@@ -13,10 +13,15 @@
 		"format": "nx format",
 		"format:uncommitted": "nx format --fix --parallel --uncommitted",
 		"lint": "nx run-many --all --target=lint",
+		"local-registry:clear": "rm -rf tmp/verdaccio",
+		"local-registry:enable": "./tools/scripts/local-registry.mjs enable",


Would there be any downside to running npm config set directly?

adamziel · 2024-12-10T09:30:25Z

Thank you @psrpinto! It looks great overall, I just left a few minor notes

psrpinto · 2024-12-10T12:29:12Z

Thanks for reviewing @adamziel!, Your notes are on point, I will work on addressing them.

psrpinto self-assigned this Dec 4, 2024

psrpinto force-pushed the test-publish-packages branch 3 times, most recently from 95d105a to e3a790e Compare December 6, 2024 13:48

psrpinto added 10 commits December 6, 2024 13:59

Add documentation section for publishing packages

cb8c855

Iterate on docs

33d2226

Install verdaccio as a devDependency

e172af3

Add scripts to start and clear the local registry

7b78152

Document how to use the local registry

2fcb71f

Add scripts to enable and disable local registry

742c23c

Reorder scripts

ae88e29

Fix spacing of .npmrc

63012af

Implement script to enable or disable local registry

ce299fb

Add a pre-commit hook

26d20c1

To prevent accidentally committing .npmrc with the registry set to local.

psrpinto force-pushed the test-publish-packages branch from e3a790e to 26d20c1 Compare December 6, 2024 14:00

psrpinto added 3 commits December 6, 2024 14:35

Configure verdaccio

e7ec369

Reorder docs

f76692e

Add script to release with no push

f6b1abd

psrpinto force-pushed the test-publish-packages branch 3 times, most recently from be485bd to fad3d74 Compare December 6, 2024 16:42

Iterate on docs

09076ae

psrpinto force-pushed the test-publish-packages branch from fad3d74 to 09076ae Compare December 6, 2024 17:00

psrpinto added [Type] Developer Experience [Type] Developer Documentation Documentation for developers labels Dec 6, 2024

psrpinto marked this pull request as ready for review December 6, 2024 17:11

psrpinto requested a review from a team as a code owner December 6, 2024 17:11

psrpinto commented Dec 6, 2024

View reviewed changes

adamziel reviewed Dec 10, 2024

View reviewed changes

adamziel mentioned this pull request Dec 16, 2024

Build @php-wasm packages as dual ESM + CJS #2087

Merged

psrpinto mentioned this pull request Dec 17, 2024

Cannot find package @php-wasm/web-service-worker #2086

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Make it easy to test-publish packages #2053

Make it easy to test-publish packages #2053

psrpinto commented Dec 4, 2024 •

edited

Loading

psrpinto left a comment

psrpinto Dec 6, 2024

adamziel Dec 10, 2024 •

edited

Loading

psrpinto Dec 6, 2024

adamziel Dec 10, 2024

adamziel Dec 10, 2024 •

edited

Loading

adamziel Dec 10, 2024 •

edited

Loading

adamziel Dec 10, 2024 •

edited

Loading

adamziel Dec 10, 2024

adamziel commented Dec 10, 2024

psrpinto commented Dec 10, 2024

	### Publishing to a local registry
	## Publishing to a local registry

Make it easy to test-publish packages #2053

Are you sure you want to change the base?

Make it easy to test-publish packages #2053

Conversation

psrpinto commented Dec 4, 2024 • edited Loading

Testing instructions

Summary of changes

Screen captures

Local package registry

Docs

References

psrpinto left a comment

Choose a reason for hiding this comment

psrpinto Dec 6, 2024

Choose a reason for hiding this comment

adamziel Dec 10, 2024 • edited Loading

Choose a reason for hiding this comment

psrpinto Dec 6, 2024

Choose a reason for hiding this comment

adamziel Dec 10, 2024

Choose a reason for hiding this comment

adamziel Dec 10, 2024 • edited Loading

Choose a reason for hiding this comment

adamziel Dec 10, 2024 • edited Loading

Choose a reason for hiding this comment

adamziel Dec 10, 2024 • edited Loading

Choose a reason for hiding this comment

adamziel Dec 10, 2024

Choose a reason for hiding this comment

adamziel commented Dec 10, 2024

psrpinto commented Dec 10, 2024

psrpinto commented Dec 4, 2024 •

edited

Loading

adamziel Dec 10, 2024 •

edited

Loading

adamziel Dec 10, 2024 •

edited

Loading

adamziel Dec 10, 2024 •

edited

Loading

adamziel Dec 10, 2024 •

edited

Loading